---
target: Umo Office Convert
keywords: Umo Office Convert,office在线预览,wps在线预览,docx在线预览,word在线预览,pdf在线预览
description: 将 Office、WPS 等 40 余种办公文档转换为可在线查看的文档格式，可与 Umo Office Viewer 结合使用实现办公文档的在线预览。
---

# 环境变量配置

`.env` 文件主要用于配置应用程序的运行环境和各项参数，实现配置与代码分离，便于不同环境（开发/测试/生产）的部署管理。通过修改配置文件即可调整应用行为，无需修改源代码，提高部署灵活性和安全性。

您需要复制根目录下的 `.env.example` 并重命名为 `.env` 放置于根目录下，并根据实际需要修改对应配置。

## 配置项说明

完整的 `.env` 文件配置示例见 `.env.example`，以下是配置项的详细说明。

### Node 环境配置
```bash
# node 环境
NODE_ENV = production
```

### 服务相关配置
```bash
# 服务端口
PORT = 1236
# 服务名称
SERVER_NAME = Umo Office Convert
```

### 日志配置
```bash
# 日志存放路径
LOG_DIR = ./logs
```

### 文件上传配置
```bash
# 最大允许上传的文件大小，单位为 MB
MAX_FILE_SIZE = 50
```

### 文档存储路径配置
```bash
# 上传的文档存放路径
UPLOAD_DIR = ./uploads/[year]/[month]
# 转换后的文档存放路径
CONVERTED_DIR = ./converted/[year]/[month]
```

### 文件哈希算法配置
```bash
FILE_HASH_ALGORITHM = sha256
```

### MySQL 数据库配置
```bash
DB_HOST = localhost
DB_PORT = 3306
DB_USER = root
DB_PASSWORD =
DB_NAME = umo_office_convert
```

### Webhook 配置
```bash
# Webhook 地址，用于接收文件上传和转换完成的通知
CONVERTED_WEBHOOK_URL =
```

### 访问控制配置
```bash
# 允许访问服务的 IP 地址列表，多个 IP 地址之间用逗号分隔，设置为 `*` 或留空表示允许所有来源
WHITE_LIST = 127.0.0.1, 0.0.0.0, localhost
```

## 重要说明

### 路径变量说明
- `[year]`、`[month]`、`[day]` 为动态路径变量，系统会根据当前日期自动替换。例如：`./uploads/[year]/[month]` 可能会生成 `./uploads/2024/01` 这样的路径
- 如果未指定上传路径，则不保存上传的文件

### 安全注意事项
1. **数据库密码**：`DB_PASSWORD` 需要根据实际环境设置
2. **白名单配置**：`WHITE_LIST` 用于限制访问 IP，生产环境建议配置具体的 IP 地址
3. **文件大小限制**：`MAX_FILE_SIZE` 可根据实际需求调整，避免服务器资源耗尽

### 哈希算法选择
- 文件哈希算法，用于生成文件的唯一标识符, 支持的算法列表会根据你使用的 Node.js 版本、操作系统和 OpenSSL 版本而异，常见的有 `md5`, `sha1`, `sha256`, `sha512` 等
- 如果更改哈希算法，需要确保数据表中的 `hash` 字段长度足够存储哈希值

### Webhook 功能
- `CONVERTED_WEBHOOK_URL` 用于接收文件处理状态通知，其配置的地址需要支持接收 `POST` 请求，且无需授权
- 当文件上传或文件转换完成后，系统会向配置的 Webhook URL 发送 POST 请求，包含转换任务的相关信息。
- 留空或不配置则表示不启用 Webhook 功能
